The World of Computer Software

home *** CD-ROM | disk | FTP | other *** search

/ The World of Computer Software / The World of Computer Software.iso / qdpmi101.zip / QDPMI.DOC < prev next >

Wrap

Text File | 1993-01-04 | 22KB | 508 lines

========================================================================= Quarterdeck Office Systems QDPMI Host V1.01 ========================================================================= NOTICE TO END USERS: THIS SOFTWARE MAY BE FREELY COPIED, HOWEVER YOUR ACTUAL USE OF QDPMI IS CONDITIONED UPON (i) YOUR POSSESSION OF AN AUTHORIZED COPY OF QEMM-386 AND (ii) YOUR COMPLIANCE WITH THE TERMS OF THE QEMM-386 QUARTERDECK END USER LICENSE AGREEMENT, WHICH GOVERNS USE OF THIS SOFTWARE. Copyright (c) Quarterdeck Office Systems, Inc. 1986-1992. ALL RIGHTS RESERVED. DOS Extension Technology by ERGO Computing, Inc. Copyright (c) 1991-1992. ALL RIGHTS RESERVED. ========================================================================= INTRODUCTION ------------ The Quarterdeck DPMI Host (QDPMI) is a companion product to the Quarterdeck Expanded Memory Manager-386 (QEMM-386). It is a full implementation of Version 0.9 of the DOS Protected Mode Interface (DPMI) specification, including MS-DOS extensions and virtual memory. DPMI is an emerging industry standard for allowing DOS applications to access the protected mode features of the 80386 and 80486 processors. To DOS application users this means that an application can now be larger and more full featured than those applications restricted to 640K. The DPMI specification was developed by a consortium of computer companies, including Quarterdeck, Borland, Ergo, IBM, Intel, Intelligent Graphics, Locus, Lotus Development, Microsoft, Phar Lap, Phoenix Technologies and Rational Systems. Protected mode multitasking environments, memory managers, or operating systems that implement DPMI functions are called DPMI hosts. Protected mode applications that request DPMI functions (directly or indirectly) are called DPMI clients. DOS applications using DPMI (DPMI clients) can run in a variety of operating environments, including DOS, DR DOS, Microsoft Windows, OS/2, 386-based UNIX, DESQview 386 and DESQview/X provided a DPMI host is present. The Quarterdeck DPMI Host (QDPMI) provides mode-switching and extended memory management to DPMI clients. It runs at a more privileged level than its clients and uses the hardware to enforce a supervisor/user protection model. This allows QDPMI to support centralized virtual memory and maintain full control over client programs' address spaces and access to hardware. Users of Quarterdeck's DESQview 386 and DESQview/X can run multiple QDPMI clients simultaneously, each optionally having its own virtual memory. Software Compatibility ---------------------- DOS applications that support the DPMI specification are just coming to market. The earliest of these are programmer's tools including Microsoft's C/C++ Development System for Windows (version 7), Borland's C++ (version 3) and Intel's Code Builder Kit (version 1.1). QDPMI is compatible with the above programs. Microsoft Windows version 3.1 includes its own DPMI host. When QDPMI sees Windows Enhanced Mode start up, it steps aside, letting Windows provide the DPMI services for programs running in its environment. About This Manual ----------------- This manual is your reference guide to the Quarterdeck DPMI Host (QDPMI). This manual tells you: o How to install QDPMI. o How to specify whether virtual memory is to be used and the amount of virtual memory to be reserved. o About the command line parameters available with QDPMI. The Quarterdeck DPMI Host (QDPMI) requires the Quarterdeck Expanded Memory Manager (QEMM-386) for its services to be made available to DPMI client programs. So before you install QDPMI, please check that QEMM-386 is installed on your system. Installing QDPMI is easy. All you must do is run the QDPMI installation program, INSTALL. During installation, INSTALL will display several screens, either to ask for information or to inform you of its progress. If QEMM-386 is not currently installed in your system, INSTALL will post a warning message, telling you that QEMM-386 was not found in your CONFIG.SYS file and telling you to install it. As mentioned earlier, QDPMI will not work without QEMM- 386. INSTALL will need to know where to copy QDPMI files. The default drive and directory is C:\QEMM. Next INSTALL will ask you whether you would like QDPMI to provide virtual memory support for each DPMI client you run. If you answer Yes, you must then indicate how much disk space should be allocated for the virtual memory swap file. The default is 1024K per DPMI client. When QDPMI uses virtual memory, it creates a virtual memory swap file. INSTALL next asks you whether QDPMI should automatically delete the virtual memory swap file when your application terminates. Creating and deleting the virtual memory swap file takes more time, but conserves disk space. When you have answered the above questions, INSTALL automatically creates the necessary change to your AUTOEXEC.BAT and CONFIG.SYS files needed by DOS to load QDPMI, and offers to modify these files for you. Then it copies the QDPMI files to the drive and directory you indicated. Installing QDPMI from floppy ---------------------------- To install QDPMI from the QDPMI diskette: Place the QDPMI disk in drive A. Type A:INSTALL and press Enter. Installing QDPMI by downloading from the Quarterdeck BBS -------------------------------------------------------- If you have downloaded the QDPMI files from a Quarterdeck bulletin board into a drive/directory on your hard disk: Change to the drive and directory where the QDPMIZIP.EXE file you downloaded from the bulletin board is stored. Type QDPMIZIP and press Enter. NOTE: QDPMIZIP.EXE is a self-extracting zip file that when run will extract three files, INSTALL.EXE, LICENSE.TXT, and QDPMI.QIP into the current directory. Now type INSTALL and press Enter. QDPMI Installation Program -------------------------- NOTE: If you have an LCD or Gas Plasma display, as on some laptops, or a monochrome monitor, we recommend that you run INSTALL in monochrome mode by typing X:INSTALL/m (where X: is the drive and directory containing the QDPMI files. Follow the instructions on the screen. INSTALL copies the QDPMI files to your hard disk and configures QDPMI. It is always a good idea when making changes to your system configuration to run QEMM-386's Optimize program after making your changes. This will insure the best use of your system's memory. After successfully completing the QDPMI installation procedure, it will be necessary to reboot your system to begin using QDPMI. If you want to check that DPMI is working, typing QDPMI at the DOS command line without any parameters will display the current status of QDPMI. That's all there is to installing QDPMI. Installation Notes ------------------ QDPMI Client Initialization with Virtual Memory ----------------------------------------------- At DPMI client initialization time (when an application that requires DPMI services is run), QDPMI will attempt to create the virtual memory swap file whose name and maximum size appear in the QDPMI environment variable. If the swap file name is not specified in the QDPMI environment variable, the file will be opened or created in the directory from which QDPMI.SYS was loaded at system startup, with the base name QDPMI.SWP. If the swap file exists, it will be used. Its existing size will be truncated to zero length, and increased as needed by QDPMI. If the KILLSWAP option is specified, QDPMI will delete the virtual memory swap file upon the termination of the DPMI client application. In multitasking environments such as DESQview and DESQview/X, each task or DESQview window can have its own unique set of QDPMI switches and QDPMI environment variable options in force. It is necessary that each simultaneously executing DPMI client application utilizing virtual memory have its own unique virtual memory swap file. The name of the swap file that is provided in the QDPMI environment variable is therefore modified by QDPMI before it is opened or created, by appending a digit to the end of its base name. For example: QDPMI.SWP would become QDPMI0.SWP, and QDPMISWP.SWP would become QDPMISW0.SWP. The actual digit will vary depending on whether DESQview is active or not, and how many other DPMI clients are active in other DOS partitions. If for some reason QDPMI cannot find or create its virtual memory swapfile, it will issue a message and disable the virtual memory feature for the current client's invocation. Causes for this may be: o Insufficient disk space. o Improperly specified Swap File name (QDPMI environment variable). o Non-existent directory specified. System Interrupt Stack Configuration ------------------------------------ It is important for some applications that a line exist in CONFIG.SYS setting up system interrupt stack configuration. The suggested values are: stacks = 9,256 This means that DOS should allocate nine system stacks, each 256 bytes in size. The default for this setting is: stacks = 9,128 Under QDPMI, this may not be sufficient. Novell Netware -------------- QDPMI has the capability to support either 16- or 32- bit DPMI clients. When a 32 bit client is executing, it expects all 32 bits of the processor's 32- bit registers to be preserved across interrupts. There are some device drivers and TSRs that utilize the 80x86's 32 bit registers, but do not preserve them, causing undesirable erratic behavior of 32 bit DPMI clients. A notable example is Novell's LAN WorkPlace for DOS v4.01 (TCPIP.EXE). Running the supplied TSR program LWPFIX.COM after loading the LAN WorkPlace TCPIP driver will prevent this erratic behavior. NOTE: Novell has addressed this problem, and later releases will have the appropriate corrections. Borland C/C++ 3.1 ----------------- Borland's compiler can allocate memory through both EMS and DPMI APIs. Since QDPMI hasn't the means to limit EMS allocation by its clients, it is possible for QDPMI's memory resources to be depleted without QDPMI's knowledge. This can be prevented however by limiting the EMS usage of the compiler through the use of the Borland compile-time switch -Qe=xxxx or -Qe-. The former tells Borland's compiler not to exceed xxxx K of EMS memory for use as a swap buffer. The latter tells the compiler to use NO EMS for swapping purposes when compiling. The recommended setting is -Qe-, as all necessary swapping will be performed by QDPMI. QDPMI Reference --------------- This chapter is the reference guide for command line parameters used with both QDPMI.SYS as well as QDPMI.COM programs. This chapter also explains the way to use the QDPMI environment variable to further control QDMPI's behavior. QDPMI Command Line Parameters ----------------------------- Both QDPMI.SYS and QDPMI.COM respond to the same set of command line parameters. Command line parameters may be used on the QDPMI device driver line in CONFIG.SYS to initially set QDPMI's options. QDPMI.COM may also be used to modify any or all QDPMI's options from the DOS command line at a later time. To use a QDPMI.SYS command line parameter, you type the parameter name on the same line as DEVICE=C:\QEMM\QDPMI.SYS in your CONFIG.SYS file. To use a QDPMI.COM command line parameter you type QDPMI followed by the parameter name at the DOS prompt. You may use an abbreviation instead of the parameter name. The abbreviation for each QDPMI command line parameter is shown below in parentheses after each parameter name. The QDPMI command line parameters are: DPMI (ON) turns DPMI 0.9 services on. This is a default setting. NODPMI (OFF) turns DPMI services off. VMON (VM) turns QDPMI virtual memory on. This is the default setting. VMOFF (NOVM) turns QDPMI virtual memory off. KILLSWAP (KLSW) causes the QDPMI host to delete its virtual memory swap file at the termination of the DPMI client application. This is the default setting. KEEPSWAP (KPSW) causes the QDPMI host not to delete its virtual memory swap file at the termination of the DPMI client application. EXTCHKON (XCHK) causes the QDPMI host to step out of the way for incompatible DOS extenders that prefer to do all of their own DOS extender work in their own way. This is the default setting. EXTCHOFF (NOXCHK) causes the QDPMI host not to step out of the way for incompatible DOS extenders that prefer to do all of their own DOS extender work in their own way. OVLDIR=<path> Specifies where QDPMI will look for its QDPMIVM.OVL file at DPMI client initialization. This defaults to the same directory from which QDPMI.SYS was loaded at system initialization. Under some network implementations such as diskless workstations however, this initial path may cease to exist after the system is initialized. Use this switch tell QDPMI where to look for QDPMIVM.OVL at DPMI client initialization in such cases. The QDPMI Environment Variable ------------------------------ QDPMI looks at an environment variable to determine information regarding its configuration. The environment variable is QDPMI. Its syntax is as follows: SET QDPMI=[MAXLOW <aaaa>] [MINMEM <bbbb>] [MAXMEM <cccc>] [SWAPFILE <filename> [dddd]] NOTE: The environment variable line must appear in your AUTOEXEC.BAT file as one line. The QDPMI environment variable is not required to be set for QDPMI's services to be utilized. QDPMI will use a set of default values in the absence of user specified ones. All individual parameters within the QDPMI environment variable are also optional, and may be specified in any order. MAXMEM <cccc> is the maximum number of kilobytes of physical memory that will be reserved by QDPMI. This can be any number up to the amount of physical memory available on your system, and will be allocated from VCPI, XMS, extended, and conventional memory resources, in that order. The memory used by QDPMI includes all memory for use by its code, data, and page tables, as well as memory requested for use by the DPMI client application. If MAXMEM is greater than the available physical memory, or greater than external limits placed on extended memory resources by multitaskers such as DESQview, MAXMEM will be adjusted downward to be within those limits. The default value is the total amount of physical memory installed in yours system. If omitted or explicitly set to zero, MAXMEM is set to the largest value supported on your system. This will either be the size of all of your physical memory, or that which is available to the current partition of DESQview, whichever is smaller. MINMEM <bbbb> is the amount of physical memory in kilobytes that will be reserved by QDPMI immediately upon DPMI client application initialization for use by the QDPMI kernel itself. QDPMI will not initialize if less than this amount of memory is available for its use. The default value for MINMEM varies depending on the amount of physical memory installed in your computer, and whether you are using QDPMI's Virtual Memory features. Any attempt to set MINMEM to a value lower than QDPMI's calculated minimum will result in QDPMI ignoring the request, and using its own calculated MINMEM value. MAXMEM must be greater than or equal to MINMEM, regardless of whether it was user specified or internally calculated. If this is not the case, QDPMI will exit with a message indicating that insufficient memory is available for its initialization. The difference between MAXMEM and MINMEM is the amount of memory that will be managed dynamically by QDPMI, and made available to other applications (including other DPMI clients) when freed. This dynamic memory pool is managed through the use of VCPI memory only. MAXLOW <aaaa> is the maximum number of kilobytes of conventional DOS memory allowed to be reserved by QDPMI for use as its memory resources. Setting it to any non-zero value will allow QDPMI to allocate DOS conventional memory for use in its memory pool. Note that QDPMI will only resort to using DOS conventional memory if expanded and extended memory resources are insufficient to satisfy the MINMEM request. The default value is 0. Conventional memory is only used if MINMEM cannot be satisfied from other resources, and only if this value is non-zero. SWAPFILE <filename> [<dddd>] is the base name of the virtual memory swapfile that QDPMI will use, optionally followed by its maximum size in kilobytes. The size of the virtual memory swapfile that you specify may be any value up to 64 megabytes, and defaults to 1MB. Virtual Memory Total Memory Size -------------------------------- The SUM of the value of MAXMEM and the maximum size of the virtual swapfile is the amount of virtual memory (in kilobytes) available to QDPMI client applications when the virtual memory option is enabled. Error Messages -------------- QDPMI may display error messages when trying to load QDPMI or when trying to initialize a DPMI client. In addition, error messages may also be generated by the QDPMI kernel or the DOS extender. QDPMI.COM error messages are as follows: ---------------------------------------- QDPMI: Client already active -- Cannot modify parameters. A DPMI client has spawned COMMAND.COM, and is still active in the current DOS partition. It is inappropriate to change QDPMI parameters while a QDPMI client is currently running. This condition can sometimes be caused by the abnormal termination of a DPMI client. QDPMI: Already supported -- Not reloaded. Another DPMI Host other than Quarterdeck's has been detected. Quarterdeck's QDPMI is not loaded. QDPMI: Version incompatibility error -- Re-install or use same version. This message only appears if the device driver QDPMI.SYS and the utility program QDPMI.COM are not the same version. This is an error in installation or updating. You must re-install QDPMI. QDPMI: Cannot locate QEMM386.SYS Memory Manager -- Not loaded. Quarterdeck's QDPMI Host will only function in conjunction with Quarterdeck's QEMM-386 Memory Manager. QDPMI: Error accessing XDI -- Not loaded. The QDPMI Host has encountered an error initializing its XDI interface and cannot load. QDPMI: Too Many DPMI Processes -- Not loaded. The QDPMI Host has the capability of supporting up to 15 concurrent processes under DESQview and DESQview/X. If there are more than 15 windows on the screen, and a DPMI client is started in the 16th or higher window, the DPMI client will fail to initialize, and QDPMI.COM will display this message if run in this window. QDPMI: Overlay File Path/Name is too long. The QDPMIVM.OVL files (and their paths) are too long. Use a path less removed from the root. QDPMI: Quarterdeck QDPMI Host is not resident. QDPMI.COM issues this message if run without having previously loaded QDPMI.SYS in CONFIG.SYS. QDPMI client initialization messages are as follows: ---------------------------------------------------- QDPMI: Open Error. QDPMI could not open its overlay file QDPMIVM.OVL. You should make sure that it is either in the same directory as QDPMI.SYS, or in the directory specified by the OVLDIR parameter on the QDPMI command line. QDPMI: Processor Error. QDPMI must have an 80386 or higher processor in order to run. QDPMI: Read Error. QDPMI cannot read its overlay file QDPMIVM.OVL. QDPMI: Seek Error. QDPMI can not seek in its overlay file QDPMIVM.OVL. QDPMI: Close Error. QDPMI can not close its overlay file QDPMIVM.OVL. QDPMI: Bad .OVL Error. QDPMIVM.OVL file is corrupted. QDPMI: Exec Error. QDPMI could not transfer control to its overlay. QDPMI: Init Error. QDPMIVM.OVL could not complete its initialization. QDPMI: Mode Error. The QDPMI client is attempting to re-initialize the QDPMI Host in another mode (16/32 bit) than it was originally initialized. This can occur if an attempt is made to start a DPMI client of another "bitness" than the currently running DPMI client. QDPMI: Task Error. The maximum of 15 simultaneous DPMI clients are already running in other DESQview or DESQview/X windows. QDPMI: Version Error. There is a discrepancy between the QDPMI version of the device driver (QDPMI.SYS), and the kernel (QDPMIVM.OVL).